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Abstract 


Some IMAP message stores include special-use mailboxes, such as those 
used to hold draft messages or sent messages. Many mail clients 
allow users to specify where draft or sent messages should be put, 
but configuring them requires that the user know which mailboxes the 
server has set aside for these purposes. This extension adds new 
optional mailbox attributes that a server may include in IMAP LIST 
command responses to identify special-use mailboxes to the client, 
easing configuration. 


Status of This Memo 
This is an Internet Standards Track document. 


This document is a product of the Internet Engineering Task Force 


(IETF). It represents the consensus of the IETF community. It has 
received public review and has been approved for publication by the 
Internet Engineering Steering Group (IESG). Further information on 


Internet Standards is available in Section 2 of RFC 5741. 


Information about the current status of this document, any errata, 
and how to provide feedback on it may be obtained at 
http://www.rfc-editor.org/info/rfc6154. 


Copyright Notice 


Copyright (c) 2011 IETF Trust and the persons identified as the 
document authors. All rights reserved. 


This document is subject to BCP 78 and the IETF Trust’s Legal 
Provisions Relating to IETF Documents 
(http://trustee.ietf.org/license-info) in effect on the date of 
publication of this document. Please review these documents 
carefully, as they describe your rights and restrictions with respect 
to this document. Code Components extracted from this document must 
include Simplified BSD License text as described in Section 4.e of 
the Trust Legal Provisions and are provided without warranty as 
described in the Simplified BSD License. 
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Introduction 


Some IMAP message stores include special-use mailboxes, such as those 
used to hold draft messages or sent messages. Many mail clients 
allow users to specify where draft or sent messages should be put, 
but configuring them requires that the user know which mailboxes the 
server has set aside for these purposes. This extension adds new 
optional mailbox attributes that a server may include in IMAP LIST 
command responses to identify special-use mailboxes to the client, 
easing configuration. 


In addition, this extension adds an optional parameter on the IMAP 
CREATE command, allowing a client to assign a special use to a 
mailbox when it is created. Servers may choose to support this part 
of the extension, but are not required to. 


1. Conventions Used in This Document 
In examples, "C:" indicates lines sent by a client that is connected 
to a server. "S:" indicates lines sent by the server to the client. 


The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 
"SHOULD", “SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in RFC 2119 [RFC2119]. 


New Mailbox Attributes Identifying Special-Use Mailboxes 


An IMAP server that supports this extension MAY include any or all of 
the following attributes in responses to the non-extended IMAP LIST 
command. The new attributes are included along with existing 
attributes, such as "\Marked" and "\Noselect". A given mailbox may 
have none, one, or more than one of these attributes. In some cases, 
a special use is advice to a client about what to put in that 
mailbox. In other cases, it’s advice to a client about what to 
expect to find there. There is no capability string related to the 
support of special-use attributes on the non-extended LIST command. 


For the extended list command [RFC5258], this extension adds a new 
capability string, a new selection option, and a new return option, 
all called "SPECIAL-USE". Supporting implementations MUST include 
the "SPECIAL-USE" capability string in response to an IMAP CAPABILITY 
command. If the client specifies the "SPECIAL-USE" selection option, 
the LIST command MUST return only those mailboxes that have a 
special-use attribute set. If the client specifies the "SPECIAL-USE" 
return option, the LIST command MUST return the new special-use 
attributes on those mailboxes that have them set. The "SPECIAL-USE" 
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return option is implied by the "SPECIAL-USE" selection option. The 
extended LIST command MAY return SPECIAL-USE attributes even if the 
client does not specify the return option. 


The new attributes defined here are as follows: 


\All 
This mailbox presents all messages in the user’s message store. 
Implementations MAY omit some messages, such as, perhaps, those 
in \Trash and \Junk. When this special use is supported, it is 
almost certain to represent a virtual mailbox. 


\Archive 
This mailbox is used to archive messages. The meaning of an 
"archival" mailbox is server-dependent; typically, it will be 
used to get messages out of the inbox, or otherwise keep them 
out of the user’s way, while still making them accessible. 


\Drafts 
This mailbox is used to hold draft messages -- typically, 
messages that are being composed but have not yet been sent. In 
some server implementations, this might be a virtual mailbox, 
containing messages from other mailboxes that are marked with 
the "\Draft" message flag. Alternatively, this might just be 
advice that a client put drafts here. 


\Flagged 
This mailbox presents all messages marked in some way as 
"important". When this special use is supported, it is likely 
to represent a virtual mailbox collecting messages (from other 
mailboxes) that are marked with the "\Flagged" message flag. 


\Junk 
This mailbox is where messages deemed to be junk mail are held. 
Some server implementations might put messages here 
automatically. Alternatively, this might just be advice to a 
client-side spam filter. 


\Sent 
This mailbox is used to hold copies of messages that have been 
sent. Some server implementations might put messages here 
automatically. Alternatively, this might just be advice that a 
client save sent messages here. 


\Trash 
This mailbox is used to hold messages that have been deleted or 
marked for deletion. In some server implementations, this might 
be a virtual mailbox, containing messages from other mailboxes 
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that are marked with the "\Deleted" message flag. 

Alternatively, this might just be advice that a client that 
chooses not to use the IMAP "\Deleted" model should use this as 
its trash location. In server implementations that strictly 
expect the IMAP "\Deleted" model, this special use is likely not 
to be supported. 


All of the above attributes are OPTIONAL, and any given server or 
message store may support any combination of the attributes, or none 
at all. In most cases, there will likely be at most one mailbox with 
a given attribute for a given user, but in some server or message 
store implementations it might be possible for multiple mailboxes to 
have the same special-use attribute. 


Special-use attributes are likely to be user-specific. User Adam 
might share his \Sent mailbox with user Barb, but that mailbox is 
unlikely to also serve as Barb’s \Sent mailbox. It’s certainly 
possible for Adam and Barb to each set the \Sent use on the same 
mailbox, but that would be done by specific action (see the sections 
below). 


3. Extension to IMAP CREATE Command to Set Special-—-Use Attributes 


As an OPTIONAL feature, a server MAY allow clients to designate a 
mailbox, at creation, as having one or more special uses. This 
extension defines the "USE" parameter to the IMAP CREATE command for 
that purpose (using the syntax defined in RFC 4466 section 2.2 


[RFC4466]). The new OPTIONAL "USE" parameter is followed by a 
parenthesized list of zero or more special-use attributes, as defined 
above. 


In some server implementations, some special uses may imply automatic 
action by the server. For example, creation of a "\Junk" mailbox 
might cause the server to start placing messages that have been 
evaluated as spam into the mailbox. 


In some server implementations, some special uses may result ina 
mailbox with unusual characteristics or side effects. For example, 
creation of an "\Al11" mailbox might cause the server to create a 
virtual mailbox, rather than a standard one, and that mailbox might 
behave in unexpected ways (COPY into it might fail, for example). 


Servers MAY allow the creation of a special-use mailbox even if one 
so designated already exists. This might have the effect of moving 
the special use from the old mailbox to the new one, or might create 
multiple mailboxes with the same special use. Alternatively, servers 
MAY refuse the creation, considering the designation to be a 
conflict. 
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If the server cannot create a mailbox with the designated special use 
defined, for whatever reason, it MUST NOT create the mailbox, and 
MUST respond to the CREATE command with a tagged NO response. If the 
reason for the failure is related to the special-use attribute (the 
specified special use is not supported or cannot be assigned to the 
specified mailbox), the server SHOULD include the new "USEATTR" 
response code in the tagged response (see Section 5.3 for an 
example). 


An IMAP server that supports this OPTIONAL feature will advertise the 
"CREATE-SPECIAL-USE" capability string. Clients MUST NOT use the 
"USE" parameter unless the server advertises the capability. Note 
that this capability string is different from the "SPECIAL-USE" 
string defined above, and a server that supports both functions MUST 
advertise both capability strings. 


4. IMAP METADATA Entry for Special—-Use Attributes 


If a server supports this extension and the METADATA extension 
[RFC5464], it SHOULD tie the special-use attributes for a mailbox to 
its metadata entry "/private/specialuse". The value of /private/ 
specialuse is either NIL (if there are no special-use attributes for 
that mailbox) or a space-separated list of special-use attributes, 
presented the same way they would be presented in the LIST command 
response. 


Such a server MAY allow the setting of special-use attributes through 
the METADATA mechanisms, thereby allowing clients to change the 
special uses of existing mailboxes. These changes might have side 
effects, as the server automatically adjusts the special uses 
accordingly, just as it might do with CREATE USE, above. See 

Section 5.4 for an example. 


A server that supports this MUST check the validity of changes to the 
special-use attributes that are done through the metadata in the same 
way that it checks validity for the CREATE command and for any 
internal mechanisms for setting special uses on mailboxes. It MUST 
NOT just blindly accept setting of these metadata by clients, which 
might result in the setting of special uses that the implementation 
does not support, multiple mailboxes with the same special use, or 
other situations that the implementation considers invalid. 
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Examples 


.1. Example of an IMAP LIST Command 


This example shows an IMAP LIST response from a server that supports 
this extension. Note that not all of the attributes are used. This 
server also supports the Child Mailbox extension [RFC3348]. 


tl LIST we wow 
(\Marked \HasNoChildren) "/" Inbox 
(\HasNoChildren) "/" ToDo 
LIST (\HasChildren) "/" Projects 
(\Sent \HasNoChildren) "/" SentMail 
(\Marked \Drafts \HasNoChildren) "/" MyDrafts 
LIST (\Trash \HasNoChildren) "/" Trash 
1 OK done 


ANNNNNNA 


-2. Example of an Extended IMAP LIST Command 


This example shows an IMAP LIST response from a server that supports 
this extension. The client uses the extended IMAP LIST command. 


t1 CAPABILITY 
* CAPABILITY IMAP4revl SPECIAL-USE 
t1 OK done 


nna 


t2 LIST "" "S$" RETURN (SPECIAL-USE) 
(\Marked) "/" Inbox 
() "y" ToDo 
LIST () "/" Projects 
(\Sent) "/" SentMail 
(\Marked \Drafts) "/" MyDrafts 
LIST (\Trash) "/" Trash 
2 OK done 


ANNNNNNA 


Here, the client also includes the "SPECIAL-USE" selection option for 
the same list. The "SPECIAL-USE" return option could also have been 
specified, but it is unnecessary, as it is implied by the selection 
option. Note that in this case, mailboxes that do not have a 
special-use attribute are not listed. Also note that we've used the 
wildcard "*", rather than "%", to make sure we see all special-use 
mailboxes, even ones that might not be at the namespace’s root. 


t3 LIST (SPECIAL-USE) "" "x" 

* LIST (\Sent) "/" SentMail 

* LIST (\Marked \Drafts) "/" MyDrafts 
* LIST (\Trash) "/" Trash 

t3 OK done 


NNnNNA 
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5.3. Example of an IMAP CREATE Command 


This example shows an IMAP CREATE command that might be used to 
create a mailbox designated to hold draft and sent messages. It also 
attempts to create a mailbox that will contain all the user’s 
messages, but the server does not support that special use for this 
user’s message store. 


C: t1 CAPABILITY 
S: * CAPABILITY IMAP4rev1 CREATE-SPECIAL-USE 
S: t1 OK done 


Q 


t2 CREATE MySpecial (USE (\Drafts \Sent)) 
S: t2 OK MySpecial created 


t3 CREATE Everything (USE (\Al11)) 
t3 NO [USEATTR] \All not supported 


na 


5.4. Example of Using IMAP METADATA to Manipulate Special-Use 
Attributes 


This example shows how IMAP METADATA can be used to manipulate 
special-use attributes, if the operation is supported on the server. 


==> Starting point: 

C: t1 LIST "" "S$" RETURN (SPECIAL-USE) 
S: * LIST (\Sent) "/" SentMail 

S: * LIST (\Drafts) "/" MyDrafts 

S: * LIST () "/" SavedDrafts 

S: * LIST (\Trash) "/" Trash 

S: t1 OK done 


==> Demonstrate the connection: 

C: t2 GETMETADATA "MyDrafts" /private/specialuse 

S: * METADATA "MyDrafts" (/private/specialuse "\\Drafts") 
S: t2 OK done 


==> Set new use for SavedDrafts; MyDrafts changes automatically: 
C: t3 SETMETADATA "SavedDrafts" (/private/specialuse "\\Drafts") 
S: * METADATA "MyDrafts" (/private/specialuse NIL) 

S: t3 OK SETMETADATA complete 


==> Remove special use for SentMail: 


C: t4 SETMETADATA "SentMail" (/private/specialuse NIL) 
S: t4 OK SETMETADATA complete 
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==> Check the results: 


C: t5 LIST "" "S$" RETURN (SPECIAL-USE) 
S: * LIST () "/" SentMail 

S: * LIST () "/" MyDrafts 

S: * LIST (\Drafts) "/" SavedDrafts 

S: * LIST (\Trash) "/" Trash 

S: t5 OK done 


6. Formal Syntax 


The following syntax specification uses the augmented Backus-Naur 
Form (BNF) as described in [RFC5234]. 


create-param =/ "USE" SP "(" [use-attr *(SP use-attr)] ")" 
; Extends "create-param" from RFC 4466 [RFC4466] 


mbx-list-oflag =/ use-attr 
; Extends "mbx-list-oflag" from IMAP base [RFC3501] 


list-select-independent-opt =/ "SPECIAL-USE" 
; Extends "list-select-—independent-opt" from 
; LIST-extended [RFC5258] 


return-option =/ "SPECIAL-USE" 
; Extends "return-option" from 
; LIST-extended [RFC5258] 


resp-text-code =/ "“USEATTR" 
; Extends "“resp-text-code" from 
; IMAP [RFC3501] 


use-attr = "\A11" / "\Archive" / "\Drafts" / "\Flagged" / 
"\Junk" / "\Sent" / "\Trash" / use-attr-ext 


use-attr-ext = "\" atom 
; Reserved for future extensions. Clients 
; MUST ignore list attributes they do not understand 
; Server implementations MUST NOT generate 
; extension attributes except as defined by 
; future Standards-Track revisions of or 
; extensions to this specification. 


7. Security Considerations 
LIST response: 
Conveying special-use information to a client exposes a small bit of 


extra information that could be of value to an attacker. Knowing, 
for example, that a particular mailbox (\All) contains pointers to 
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every message the user has might be of particular value. If the IMAP 
channel is not protected from passive eavesdropping, this could be an 
issue. 


CREATE command "USE" parameter and metadata extension: In some server 
implementations, some special uses may imply automatic action by the 
server. For example, creation of a "\Junk" mailbox might cause the 
server to start placing messages that have been evaluated as spam 
into the mailbox. Implementors SHOULD consider the consequences of 
allowing a user (or client program) to designate the target of such 
automatic action. 


Example: If a user is allowed to give the "\Junk" attribute to a 
shared mailbox, legitimate mail that’s misclassified as junk (false 
positives) will be put into that shared mailbox, exposing the user’s 
private mail to others. The server might warn a user of that 
possibility, or might refuse to allow the specification to be made on 
a shared mailbox. (Note that this problem exists independent of this 
specification, if the server allows a user to share a mailbox that’s 
already in use for such a function.) 


8. IANA Considerations 
8.1. Registration of USEATTR IMAP Response Code 


This document defines a new IMAP response code, "USEATTR", which IANA 
added to the IMAP Response Codes registry. 


8.2. Registration of CREATE-SPECIAL-USE IMAP Capability 


This document defines a new IMAP capability, "CREATE-SPECIAL-USE", 
which IANA added to the IMAP 4 Capabilities registry. 


8.3. Registration of SPECIAL-USE IMAP Capability 


This document defines a new IMAP capability, "SPECIAL-USE", which 
IANA added to the IMAP 4 Capabilities registry. 


8.4. Registration of SPECIAL-USE Selection Option 


This document defines a new IMAP4 List Extended selection option, 
"SPECIAL-USE", which IANA added to the IMAP4 List Extended registry, 
as follows: 


To: iana@iana.org 

Subject: Registration of LIST-EXTENDED selection option SPECIAL-USE 
LIST-EXTENDED option name: SPECIAL-USE 

LIST-EXTENDED option type: SELECTION 
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Implied return option(s): SPECIAL-USE 

LIST-EXTENDED option description: Limit the list to special-use 
mailboxes only 

Published specification: RFC 6154 

Security considerations: none 

Intended usage: COMMON 

Person and email address to contact for further information: Authors’ 
Addresses at the end of RFC 6154 

Owner/Change controller: iesg@ietf.org 


8.5. Registration of SPECIAL-USE Return Option 


This document defines a new IMAP4 List Extended return option, 
"SPECIAL-USE", which IANA added to the IMAP4 List Extended registry, 
as follows: 


To: iana@iana.org 

Subject: Registration of LIST-EXTENDED return option SPECIAL-USE 
LIST-EXTENDED option name: SPECIAL-USE 

LIST-EXTENDED option type: RETURN 

LIST-EXTENDED option description: Request special-use mailbox 
information 

Published specification: RFC 6154 

Security considerations: none 

Intended usage: COMMON 

Person and email address to contact for further information: Authors’ 
Addresses at the end of RFC 6154 

Owner/Change controller: iesg@ietf.org 


8.6. Registration of SPECIAL-USE Metadata 


This document defines a new IMAP METADATA entry. IANA added the 
following to the IMAP METADATA Mailbox Entry registry: 


To: iana@iana.org 

Subject: IMAP METADATA Entry Registration 

Type: Mailbox 

Name: /private/specialuse 

Description: Defines any special-use features of a mailbox. See the 
reference specification for details of its use. 

Content-type: text/plain; charset=us-ascii 

RFC Number: RFC 6154 

Contact: MORG mailing list mailto:morg@ietf.org 
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